Skip to main content

1.3 - What You Can Build

Using BurnySc2/python-sc2 is like being handed a key to one of the most complex real-time strategy environments ever created. Your code becomes the brain of a player, and the possibilities extend far beyond just "making a bot."

Think of your journey as a ladder. Each rung represents a more complex project that builds on the skills you learned from the previous one.

The Developer's Journey

      [==============================]
      |  Competitive, Learning AI  |  (Advanced AI/ML)
      [==============================]
                  ^
                  |
      [==============================]
      |    Strategic, Reactive Bot   |  (Mid/Late-Game Logic)
      [==============================]
                  ^
                  |
      [==============================]
      |      "Clockwork" Bot       |  (Core Mechanics)
      [==============================]
                  ^
                  |
      [==============================]
      |      Specialized Tools     |  (Understanding the API)
      [==============================]

Let's break down what you can build at each stage.

Stage 1: Specialized Tools & Analyzers​

Before building a full player, it's incredibly useful to learn the API by creating small, focused tools. These projects are simple and teach you how to read the game's state without worrying about complex decision-making.

Project TypeGoal: What you're trying to do.Key python-sc2 Concepts:Skills Gained:
Observation BotRead and print game information to the console.self.state, self.units, self.structuresAccessing game data, using the game loop (on_step).
Mechanics TrainerCreate specific scenarios for a human to practice against.self.do(), unit.attack(position)Issuing basic commands, precise unit control.
Data AnalyzerRun a simulation and log the results to a file.unit.health, self.timeData collection, understanding combat outcomes.

✅ Project Idea Checklist:

  • Make a bot that prints your starting mineral and vespene count every 10 seconds.
  • Create a bot that spawns 10 Zerglings and sends them to attack a single point on the map.
  • Build a script that only builds Supply Depots (or Pylons/Overlords) until you run out of money.

Stage 2: The "Clockwork" Bot​

This is your first real bot. Its strength comes from executing a single, perfectly timed strategy (a "build order") without deviation. It won't react to the enemy, but it will teach you all the fundamental mechanics of managing an autonomous player.

Project TypeGoal: What you're trying to do.Key python-sc2 Concepts:Skills Gained:
Build Order BotFlawlessly execute a build from start to finish.self.can_afford(), self.train(), worker.build()Resource management, production queuing.
Early-Game RusherBuild an army quickly and attack the enemy base.self.enemy_start_locations, units.attack()Basic state management (e.g., "am I attacking?").

✅ Project Idea Checklist:

  • Build a "4-Gate" Protoss bot that builds 4 Gateways and attacks with Zealots.
  • Create a Zerg bot that does a "6-Pool" rush, training Zerglings as fast as possible.
  • Make a Terran bot that builds a Barracks, then a Factory, then a Starport, creating one of each unit type.

Stage 3: The Strategic, Reactive Bot​

This is where true intelligence begins. Your bot will now use the information it gathers to make decisions. It will scout, analyze the enemy, and adapt its strategy in real-time. This is the most common and rewarding type of bot to build.

Project TypeGoal: What you're trying to do.Key python-sc2 Concepts:Skills Gained:
Scouting BotSend a worker to the enemy base to see what they are building.self.enemy_units, unit.is_idle, unit.move()Information gathering, conditional logic (if/else).
Adaptive BotChange its build order based on what it scouts.unit.type_id, self.structures.existsComplex state machines, mid-game planning.
Micro-Intensive BotControl units precisely in combat (e.g., stutter-stepping).unit.weapon_cooldown, ability-specific commands.Fine-grained unit control, event-driven actions.

✅ Project Idea Checklist:

  • If your scouting worker sees the enemy is building air units, build anti-air units in response.
  • If you have more than 5 idle workers, command them to gather minerals.
  • Make your ranged units attack and move backward if an enemy gets too close.

Stage 4: The Competitive, Learning AI​

This is the frontier of bot development. These projects often involve advanced AI concepts, including machine learning, to create bots that can learn from their games and improve over time.

Project TypeGoal: What you're trying to do.Key python-sc2 Concepts:Skills Gained:
Data-Driven BotSave data from games and use it to inform future strategy.File I/O (reading/writing to disk)Data persistence, basic statistical analysis.
ML-Integrated BotUse a machine learning model to make high-level decisions.Integration with libraries like TensorFlow/PyTorch.Machine learning principles, API integration.

✅ Project Idea Checklist:

  • Save the result (win/loss) of every match along with the build order you used.
  • Create a bot that tries a random strategy, and over time, learns to prefer the ones that lead to more wins.